home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / share / automake-1.9 / Automake / VarDef.pm < prev    next >
Encoding:
Perl POD Document  |  2005-10-13  |  9.0 KB  |  357 lines
  1. # Copyright (C) 2003, 2004  Free Software Foundation, Inc.
  2.  
  3. # This program is free software; you can redistribute it and/or modify
  4. # it under the terms of the GNU General Public License as published by
  5. # the Free Software Foundation; either version 2, or (at your option)
  6. # any later version.
  7.  
  8. # This program is distributed in the hope that it will be useful,
  9. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11. # GNU General Public License for more details.
  12.  
  13. # You should have received a copy of the GNU General Public License
  14. # along with this program; if not, write to the Free Software
  15. # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  16. # 02110-1301, USA.
  17.  
  18. package Automake::VarDef;
  19. use strict;
  20. use Carp;
  21. use Automake::ChannelDefs;
  22. use Automake::ItemDef;
  23.  
  24. require Exporter;
  25. use vars '@ISA', '@EXPORT';
  26. @ISA = qw/Automake::ItemDef Exporter/;
  27. @EXPORT = qw (&VAR_AUTOMAKE &VAR_CONFIGURE &VAR_MAKEFILE
  28.           &VAR_ASIS &VAR_PRETTY &VAR_SILENT &VAR_SORTED);
  29.  
  30. =head1 NAME
  31.  
  32. Automake::VarDef - a class for variable definitions
  33.  
  34. =head1 SYNOPSIS
  35.  
  36.   use Automake::VarDef;
  37.   use Automake::Location;
  38.  
  39.   # Create a VarDef for a definition such as
  40.   # | # any comment
  41.   # | foo = bar # more comment
  42.   # in Makefile.am
  43.   my $loc = new Automake::Location 'Makefile.am:2';
  44.   my $def = new Automake::VarDef ('foo', 'bar # more comment',
  45.                                   '# any comment',
  46.                                   $loc, '', VAR_MAKEFILE, VAR_ASIS);
  47.  
  48.   # Appending to a definition.
  49.   $def->append ('value to append', 'comment to append');
  50.  
  51.   # Accessors.
  52.   my $value    = $def->value;  # with trailing `#' comments and
  53.                                # continuation ("\\\n") omitted.
  54.   my $value    = $def->raw_value; # the real value, as passed to new().
  55.   my $comment  = $def->comment;
  56.   my $location = $def->location;
  57.   my $type     = $def->type;
  58.   my $owner    = $def->owner;
  59.   my $pretty   = $def->pretty;
  60.  
  61.   # Changing owner.
  62.   $def->set_owner (VAR_CONFIGURE,
  63.                    new Automake::Location 'configure.ac:15');
  64.  
  65.   # Marking examined definitions.
  66.   $def->set_seen;
  67.   my $seen_p = $def->seen;
  68.  
  69.   # Printing a variable for debugging.
  70.   print STDERR $def->dump;
  71.  
  72. =head1 DESCRIPTION
  73.  
  74. This class gather data related to one Makefile-variable definition.
  75.  
  76. =head2 Constants
  77.  
  78. =over 4
  79.  
  80. =item C<VAR_AUTOMAKE>, C<VAR_CONFIGURE>, C<VAR_MAKEFILE>
  81.  
  82. Possible owners for variables.  A variable can be defined
  83. by Automake, in F<configure.ac> (using C<AC_SUBST>), or in
  84. the user's F<Makefile.am>.
  85.  
  86. =cut
  87.  
  88. # Defined so that the owner of a variable can only be increased (e.g
  89. # Automake should not override a configure or Makefile variable).
  90. use constant VAR_AUTOMAKE => 0; # Variable defined by Automake.
  91. use constant VAR_CONFIGURE => 1;# Variable defined in configure.ac.
  92. use constant VAR_MAKEFILE => 2; # Variable defined in Makefile.am.
  93.  
  94. =item C<VAR_ASIS>, C<VAR_PRETTY>, C<VAR_SILENT>, C<VAR_SORTED>
  95.  
  96. Possible print styles.  C<VAR_ASIS> variables should be output as-is.
  97. C<VAR_PRETTY> variables are wrapped on multiple lines if they cannot
  98. fit on one.  C<VAR_SILENT> variables are not output at all.  Finally,
  99. C<VAR_SORTED> variables should be sorted and then handled as
  100. C<VAR_PRETTY> variables.
  101.  
  102. C<VAR_SILENT> variables can also be overridden silently (unlike the
  103. other kinds of variables whose overridding may sometimes produce
  104. warnings).
  105.  
  106. =cut
  107.  
  108. # Possible values for pretty.
  109. use constant VAR_ASIS => 0;    # Output as-is.
  110. use constant VAR_PRETTY => 1;    # Pretty printed on output.
  111. use constant VAR_SILENT => 2;    # Not output.  (Can also be
  112.                 # overridden silently.)
  113. use constant VAR_SORTED => 3;    # Sorted and pretty-printed.
  114.  
  115. =back
  116.  
  117. =head2 Methods
  118.  
  119. C<VarDef> defines the following methods in addition to those inherited
  120. from L<Automake::ItemDef>.
  121.  
  122. =over 4
  123.  
  124. =item C<my $def = new Automake::VarDef ($varname, $value, $comment, $location, $type, $owner, $pretty)>
  125.  
  126. Create a new Makefile-variable definition.  C<$varname> is the name of
  127. the variable being defined and C<$value> its value.
  128.  
  129. C<$comment> is any comment preceding the definition.  (Because
  130. Automake reorders variable definitions in the output, it also tries to
  131. carry comments around.)
  132.  
  133. C<$location> is the place where the definition occured, it should be
  134. an instance of L<Automake::Location>.
  135.  
  136. C<$type> should be C<''> for definitions made with C<=>, and C<':'>
  137. for those made with C<:=>.
  138.  
  139. C<$owner> specifies who owns the variables, it can be one of
  140. C<VAR_AUTOMAKE>, C<VAR_CONFIGURE>, or C<VAR_MAKEFILE> (see these
  141. definitions).
  142.  
  143. Finally, C<$pretty> tells how the variable should be output, and can
  144. be one of C<VAR_ASIS>, C<VAR_PRETTY>, or C<VAR_SILENT>, or
  145. C<VAR_SORTED> (see these definitions).
  146.  
  147. =cut
  148.  
  149. sub new ($$$$$$$$)
  150. {
  151.   my ($class, $var, $value, $comment, $location, $type, $owner, $pretty) = @_;
  152.  
  153.   # A user variable must be set by either `=' or `:=', and later
  154.   # promoted to `+='.
  155.   if ($owner != VAR_AUTOMAKE && $type eq '+')
  156.     {
  157.       error $location, "$var must be set with `=' before using `+='";
  158.     }
  159.  
  160.   my $self = Automake::ItemDef::new ($class, $comment, $location, $owner);
  161.   $self->{'value'} = $value;
  162.   $self->{'type'} = $type;
  163.   $self->{'pretty'} = $pretty;
  164.   $self->{'seen'} = 0;
  165.   return $self;
  166. }
  167.  
  168. =item C<$def-E<gt>append ($value, $comment)>
  169.  
  170. Append C<$value> and <$comment> to the exisiting value and comment of
  171. C<$def>.  This is normally called on C<+=> definitions.
  172.  
  173. =cut
  174.  
  175. sub append ($$$)
  176. {
  177.   my ($self, $value, $comment) = @_;
  178.   $self->{'comment'} .= $comment;
  179.  
  180.   my $val = $self->{'value'};
  181.  
  182.   # Strip comments from augmented variables.  This is so that
  183.   #   VAR = foo # com
  184.   #   VAR += bar
  185.   # does not become
  186.   #   VAR = foo # com bar
  187.   # Furthermore keeping `#' would not be portable if the variable is
  188.   # output on multiple lines.
  189.   $val =~ s/ ?#.*//;
  190.  
  191.   if (chomp $val)
  192.     {
  193.       # Insert a backslash before a trailing newline.
  194.       $val .= "\\\n";
  195.     }
  196.   elsif ($val)
  197.     {
  198.       # Insert a separator.
  199.       $val .= ' ';
  200.     }
  201.   $self->{'value'} = $val . $value;
  202.   # Turn ASIS appended variables into PRETTY variables.  This is to
  203.   # cope with `make' implementation that cannot read very long lines.
  204.   $self->{'pretty'} = VAR_PRETTY if $self->{'pretty'} == VAR_ASIS;
  205. }
  206.  
  207. =item C<$def-E<gt>value>
  208.  
  209. =item C<$def-E<gt>type>
  210.  
  211. =item C<$def-E<gt>pretty>
  212.  
  213. Accessors to the various constituents of a C<VarDef>.  See the
  214. documentation of C<new>'s arguments for a description of these.
  215.  
  216. =cut
  217.  
  218. sub value ($)
  219. {
  220.   my ($self) = @_;
  221.   my $val = $self->raw_value;
  222.   # Strip anything past `#'.  `#' characters cannot be escaped
  223.   # in Makefiles, so we don't have to be smart.
  224.   $val =~ s/#.*$//s;
  225.   # Strip backslashes.
  226.   $val =~ s/\\$/ /mg;
  227.   return $val;
  228. }
  229.  
  230. sub raw_value ($)
  231. {
  232.   my ($self) = @_;
  233.   return $self->{'value'};
  234. }
  235.  
  236. sub type ($)
  237. {
  238.   my ($self) = @_;
  239.   return $self->{'type'};
  240. }
  241.  
  242. sub pretty ($)
  243. {
  244.   my ($self) = @_;
  245.   return $self->{'pretty'};
  246. }
  247.  
  248. =item C<$def-E<gt>set_owner ($owner, $location)>
  249.  
  250. Change the owner of a definition.  This usually happens because
  251. the user used C<+=> on an Automake variable, so (s)he now owns
  252. the content.  C<$location> should be an instance of L<Automake::Location>
  253. indicating where the change took place.
  254.  
  255. =cut
  256.  
  257. sub set_owner ($$$)
  258. {
  259.   my ($self, $owner, $location) = @_;
  260.   # We always adjust the location when the owner changes (even for
  261.   # `+=' statements).  The risk otherwise is to warn about
  262.   # a VAR_MAKEFILE variable and locate it in configure.ac...
  263.   $self->{'owner'} = $owner;
  264.   $self->{'location'} = $location;
  265. }
  266.  
  267. =item C<$def-E<gt>set_seen>
  268.  
  269. =item C<$bool = $def-E<gt>seen>
  270.  
  271. These function allows Automake to mark (C<set_seen>) variable that
  272. it has examined in some way, and latter check (using C<seen>) for
  273. unused variables.  Unused variables usually indicate typos.
  274.  
  275. =cut
  276.  
  277. sub set_seen ($)
  278. {
  279.   my ($self) = @_;
  280.   $self->{'seen'} = 1;
  281. }
  282.  
  283. sub seen ($)
  284. {
  285.   my ($self) = @_;
  286.   return $self->{'seen'};
  287. }
  288.  
  289. =item C<$str = $def-E<gt>dump>
  290.  
  291. Format the contents of C<$def> as a human-readable string,
  292. for debugging.
  293.  
  294. =cut
  295.  
  296. sub dump ($)
  297. {
  298.   my ($self) = @_;
  299.   my $owner = $self->owner;
  300.  
  301.   if ($owner == VAR_AUTOMAKE)
  302.     {
  303.       $owner = 'Automake';
  304.     }
  305.   elsif ($owner == VAR_CONFIGURE)
  306.     {
  307.       $owner = 'Configure';
  308.     }
  309.   elsif ($owner == VAR_MAKEFILE)
  310.     {
  311.       $owner = 'Makefile';
  312.     }
  313.   else
  314.     {
  315.       prog_error ("unexpected owner");
  316.     }
  317.  
  318.   my $where = $self->location->dump;
  319.   my $comment = $self->comment;
  320.   my $value = $self->raw_value;
  321.   my $type = $self->type;
  322.  
  323.   return "{
  324.       type: $type=
  325.       where: $where      comment: $comment
  326.       value: $value
  327.       owner: $owner
  328.     }\n";
  329. }
  330.  
  331. =back
  332.  
  333. =head1 SEE ALSO
  334.  
  335. L<Automake::Variable>, L<Automake::ItemDef>.
  336.  
  337. =cut
  338.  
  339. 1;
  340.  
  341. ### Setup "GNU" style for perl-mode and cperl-mode.
  342. ## Local Variables:
  343. ## perl-indent-level: 2
  344. ## perl-continued-statement-offset: 2
  345. ## perl-continued-brace-offset: 0
  346. ## perl-brace-offset: 0
  347. ## perl-brace-imaginary-offset: 0
  348. ## perl-label-offset: -2
  349. ## cperl-indent-level: 2
  350. ## cperl-brace-offset: 0
  351. ## cperl-continued-brace-offset: 0
  352. ## cperl-label-offset: -2
  353. ## cperl-extra-newline-before-brace: t
  354. ## cperl-merge-trailing-else: nil
  355. ## cperl-continued-statement-offset: 2
  356. ## End:
  357.